Installing ProtectToolkit 7 on Unix/Linux manually
Note
Thales does not recommend using the method of installation described in this section. Use the Unix Installation Utility (safeNet-install.sh) instead as it is more likely to result in a problem-free installation or uninstallation. For more information about this method, refer to Installing ProtectToolkit 7 on Unix/Linux.
This section describes the commands you can use to install and uninstall ProtectToolkit components manually after extracting the installation files you downloaded from the Thales Support Portal.
Refer to the prerequisites below before proceeding and the post-installation configuration steps after installation.
Note
If you are installing a patch version of ProtectToolkit on an AIX system, first install the initial release of the matching minor version of ProtectToolkit.
Prerequisites
Complete the following steps before installing ProtectToolkit 7:
-
Review the Operating modes as they apply to your HSM deployment.
-
Review Supported platforms to ensure that your operating system is supported.
-
Ensure that your ProtectServer 3 HSM is installed and configured for access over a network (if applicable):
If you are setting up ProtectToolkit to run in Software Emulation Mode, HSM setup is unnecessary.
-
If you are operating the ProtectServer 3 HSM in PCIe mode on Linux, install the dkms package on the client machine.
-
Become the super-user on the host system.
Installing a component manually
The following section describes how to install a component manually on Linux.
To install a component manually
Run the following command while specifying the chosen location for the installation files:
# cd <installation_package_subdirectory>
rpm -i <installation_package_name>
For a complete list of available components, installation package names, and installation package subdirectories, refer to refer to Available ProtectToolkit 7 components.
Note
If installing SafeNet ProtectServer PCIe HSM Access Provider (K7) - device driver and the compile fails, or the driver does not come up automatically (hsmstate fails), you will need to correct the problem and then cd /opt/ETpcihsm/src and invoke make(1) as root. The Makefile in that directory has some notes to help you get the driver compiled correctly.
Further installation steps
ProtectToolkit-C installation
If you installed SafeNet ProtectToolkit C Runtime or SafeNet ProtectToolkit C SDK, add the /opt/safenet/protecttoolkit7/ptk/bin directory to the execution path and the /opt/safenet/protecttoolkit7/ptk/lib directory to the library path. The following commands can be used to configure your paths for the sh(1) shell.
PATH=$PATH:/opt/safenet/protecttoolkit7/ptk/bin
export PATH
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/safenet/protecttoolkit7/ptk/lib
export LD_LIBRARY_PATH
Once installed, the software is ready to use under /opt/safenet/protecttoolkit7.
SafeNet ProtectServer PCIe HSM Access Provider (K7) - device driver installation
If you install SafeNet ProtectServer PCIe HSM Access Provider (K7) - device driver, you must run an additional script (driver-install.sh located in /opt/safenet/protecttoolkit7/pcihsm/driver/driver-install.sh) to install the PCIe driver. If a non-root user is installing the driver, complete the following steps:
-
Add the non-root user to the hsmuser group. For more information about adding users to this group, see Controlling user access to the HSM.
-
Log out of the current ssh session and log back in as the non-root user.
-
Run driver-install.sh to complete the driver installation.
If you plan to configure the client for Secure Boot, sign the PCIe driver before running the script. For more information about signing the PCIe driver for UEFI secure boot, see Signing the ProtectServer 3 PCIe driver for UEFI Secure Boot for UEFI Secure Boot.
Signing the ProtectServer 3 PCIe driver for UEFI Secure Boot
Red Hat Enterprise Linux 7/8 (RHEL 7/8) can be installed and run on systems where UEFI Secure Boot is enabled. With Secure Boot enabled, the RHEL kernel requires all kernel modules, including device drivers, to be signed by a key that is trusted by the EFI boot loader. If a module is not signed, it is prevented from loading at runtime and the dependent device will not work.
To use ProtectServer 3 PCIe in a Secure Boot-enabled environment, the driver must be signed and trusted by the OS and boot loader.
The following procedure includes:
-
Generating RSA signing keys and certificates
-
Signing the ProtectServer PCIe driver
-
Enrolling the signing public key into the system keyring
-
Loading the signed driver
Note
This procedure applies only to a CentOS 7/8 environment with UEFI Secure Boot enabled. The steps have been tested on RHEL release 7.6.1810 and 8.4. The mokutil utility on earlier versions of Red Hat might show inconsistent behavior. If you encounter problems, upgrade your OS. Steps may vary on other Linux platforms, but the general procedure is the same.
Prerequisites
-
UEFI Secure Boot must be enabled on the Linux system.
-
The ProtectServer 3 PCIe Access Provider must be installed.
-
Driver signing requires that the following tools be available on the system:
Tool Provided by package Used on Purpose openssl openssl Build system Generates public and private X.509 key pair sign-file kernel-devel Build system Perl script used to sign kernel modules perl perl Build system Perl interpreter used to run the signing script mokutil mokutil Target system Optional tool used to manually enroll the public key keyctl keyutils Target system Optional tool used to display public keys in the system key ring
To sign and load the ProtectServer 3 PCIe driver
-
Create a configuration file with parameters for generating a key pair that satisfies RHEL 7/8 kernel module signing requirements.
# vi <configuration_filename>.config
[ req ] default_bits = 4096 distinguished_name = req_distinguished_name prompt = no string_mask = utf8only x509_extensions = myexts [ req_distinguished_name ] O = Organization CN = Organization signing key emailAddress = E-mail address [ myexts ] basicConstraints=critical,CA:FALSE keyUsage=digitalSignature subjectKeyIdentifier=hash authorityKeyIdentifier=keyid
-
Use the openssl tool to generate a signing key pair. Specify the configuration file you created, and public and private keys named MOK.der and MOK.priv. You can use the default locations specified in the command below or specify your own filepaths.
# openssl req -x509 -new -nodes -utf8 -sha256 -days 36500 -batch -config <configuration_filename>.config -outform DER -out /root/MOK/MOK.der -keyout /root/MOK/MOK.priv
-
Use the Machine Owner Key utility (mokutil) to enroll your public key on the machine(s) where you wish to load the ProtectServer 3 PCIe driver. When RHEL 7/8 boots on a UEFI Secure Boot-enabled system, the keys on the MOK list are added to the system keyring.
-
Request that your public key be added to the MOK list.
# mokutil --import MOK.der
You are prompted to enter and confirm a password for the request.
-
Restart the machine.
During restart, the MOK enrollment request is noticed by
shim.efi
, which launchesMokManager.efi
so that you can complete the enrollment from the UEFI console. -
When prompted, press any key to perform MOK management.
-
From the list of options, select Enroll MOK.
-
Select Continue and then Yes to confirm that you want to enroll the key.
-
Enter the password you created for the enrollment request.
-
Select Reboot to restart the machine.
-
-
If you specified a custom location for the signing keypair, set the following variables to point to the key locations. If you specified the default locations in step 2, skip this step.
export MOK_PRIV = <dir>/MOK.priv
export MOK_PUB = <dir>/MOK.der
-
Run the provided script to build and sign the ProtectServer 3 PCIe driver so that it will be validated by Secure Boot.
/opt/safenet/protecttoolkit7/pcihsm/driver/driver-install.sh
The following section describes how to install a component manually on AIX.
To install a component manually
Run the following commands to install ProtectToolkit components manually on AIX.
SafeNet Network HSM Access Provider
# cd /output-unix/AIX/PTKnethsm
installp -i PTKnethsm.rte
ProtectToolkit C Runtime
# cd /output-unix/AIX/PTKcprt
installp -acgNQqwX -d . PTKcprt.rte
ProtectToolkit C SDK
# cd /output-unix/AIX/PTKcpsdk
installp -acgNQqwX -d . PTKcpsdk.rte
For a complete list of available components, installation package names, and installation package subdirectories, refer to refer to Available ProtectToolkit 7 components.
Note
When installing SafeNet ProtectToolkit C Runtime or SafeNet ProtectToolkit C SDK, add the /opt/safenet/protecttoolkit7/ptk/bin directory to the execution path and the /opt/safenet/protecttoolkit7/ptk/lib directory to the library path. The following commands can be used to configure your paths for the sh(1) shell.
# PATH=/opt/safenet/protecttoolkit7/ptk/bin:$PATH
# export PATH
# LIBPATH=/opt/safenet/protecttoolkit7/ptk/lib:$LIBPATH
# export LIBPATH
Once installed, the software is ready to use under /opt/safenet/protecttoolkit7.
Uninstalling a package
Run the following command to uninstall a package manually on Linux.
# rpm -e <package_name>
For a complete list of installation package names, refer to refer to Available ProtectToolkit 7 components.
Note
Exclude the ProtectToolkit version number (-x.x.x-yy
), OS architecture (x86_64
/i686
), and .rpm
extension from the package name.
Run the following command to uninstall a package manually on AIX.
installp -u <package_name>
For a complete list of installation package names, refer to refer to Available ProtectToolkit 7 components.
Post-installation configuration
After installing ProtectToolkit on Linux manually, you can do the following:
Changing the Cryptoki provider manually
This section applies to the ProtectToolkit-C SDK package only.
Different ProtectToolkit-C Cryptoki provider files are required, depending on whether you are using ProtectToolkit-C SDK with a ProtectServer 3 HSM (PCI or Network operating mode) or without a ProtectServer 3 HSM (Software Emulator operating mode). For more information about operating modes, refer to Operating modes.
Both Cryptoki provider files are installed with the ProtectToolkit-C SDK package. On Unix/Linux systems, the Software Emulator Cryptoki provider file is made active by default.
To change the Cryptoki provider manually
-
Remove the soft-link.
/opt/safenet/protecttoolkit7/ptk/lib/libcryptoki.so
-
Recreate the soft-link to point to the SafeNet HSM Cryptoki provider. For example:
The following shell commands are used to enable the HSM (executed as the super-user):
# cd /opt/safenet/protecttoolkit7/ptk/lib # rm libcryptoki.so # ln -s libcthsm.so libcryptoki.so
The following shell commands are used to enable the software emulation (executed as the super-user):
# cd /opt/safenet/protecttoolkit7/ptk/lib # rm libcryptoki.so # ln -s libctsw.so libcryptoki.so
Controlling user access to the HSM
By default, only the root user has access to the HSM. If you are using ProtectToolkit 7 in PCI mode (see Operating modes), you can specify a set of non-root users that are permitted to access the HSM by adding them to the hsmuser group.
Note
The PTK client software installation automatically creates the hsmuser group if one does not already exist on your system. The hsmuser group is retained when you uninstall PTK, allowing you to upgrade the client software while retaining the hsmuser group configuration.
Tip
Users that are not members of the hsmuser group cannot see slots when using applications or PTK utilities. If a user runs a PTK utility such as ctconf and no slots are visible, check that the user is a member of hsmuser before troubleshooting.
Before adding or removing users from the hsmuser group, ensure that you have sudo privileges on the client workstation.
Adding users to hsmuser group
To allow non-root users or applications to access the HSM, assign the users to the hsmuser group by running the following command:
sudo gpasswd --add <username> hsmuser
The users being assigned to the hsmuser group must exist on the client workstation.
Removing users from hsmuser group
To rescind a user's access to the HSM, remove from the hsmuser group by running the following command:
sudo gpasswd -d <username> hsmuser
Note
The user you delete will continue to have access to the HSM until you restart the client workstation.
Changing the Cryptoki provider manually
This section applies to the ProtectToolkit-C SDK package only.
Different ProtectToolkit-C Cryptoki provider files are required, depending on whether you are using ProtectToolkit-C SDK with a ProtectServer 3 HSM (PCI or Network operating mode) or without a ProtectServer 3 HSM (Software Emulator operating mode). For more information about operating modes, refer to Operating modes.
Both Cryptoki provider files are installed with the ProtectToolkit-C SDK package. On Unix/Linux systems, the Software Emulator Cryptoki provider file is made active by default.
To change the Cryptoki provider manually
-
Remove the soft-link.
/opt/safenet/protecttoolkit7/ptk/lib/libcryptoki.a
-
Recreate the soft-link to point to the SafeNet HSM Cryptoki provider. For example:
The following shell commands are used to enable the HSM (executed as the super-user):
# cd /opt/safenet/protecttoolkit7/ptk/lib # rm libcryptoki.a # ln -s libcthsm.a libcryptoki.a
The following shell commands are used to enable the software emulation (executed as the super-user):
# cd /opt/safenet/protecttoolkit7/ptk/lib # rm libcryptoki.a # ln -s libctsw.a libcryptoki.a